home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 011 / ludef4.dqc / ludef4.doc
Encoding:
Text File  |  1986-03-13  |  10.8 KB  |  241 lines
  1.  
  2.  File:  LUDEF4.DOC              Date:   84-08-04
  3.  Replaces: LUDEF3.DOC           Dated:  83-08-16
  4.  
  5.  From:  Gary P. Novosielski / Paul Homchick
  6.  To:    All LU users
  7.  
  8.  Subj:  .LBR format definition
  9.  
  10.         This file is a revision of and obsoletes the previous
  11.         version.  Revised material is indicated by a vertical
  12.         bar (|) to the left of the text.
  13.  
  14.  0. Introduction
  15.     There have been several requests for a formal definition of
  16.  the format of library (.LBR) files as used by the LU Library
  17.  Utility program and the LRUN command-file load-and-go utility.
  18.  
  19.     I hope that this definition will allow other programmers to
  20.  make effective use of .LBR files in their programming without
  21.  the need for detective work or guesswork about the library
  22.  format.  Enjoy.
  23.  
  24.  
  25.  1. Library Overview
  26.     A library is a disk file which is assumed to be logically
  27.  divided into one or more subparts called members.  The library
  28.  may have any filename and filetype, except that ".LBR" is
  29.  considered to be the default filetype.  Programs must assume
  30.  and may optionally require the .LBR extension on any file
  31.  which is to be treated as a library.
  32.  
  33.  2. Access Method
  34.     Libraries are usually treated as Random Record files by
  35.  programs, but must never contain unallocated "holes" which
  36.  are normally allowed in Random Record files.  A library can
  37.  therefore be safely treated as a sequential file if desired.
  38.     This allows copy programs, compacting programs, and remote
  39.  transfer programs to process the library sequentially, and to
  40.  safely make the assumption that the first occurrence of a
  41.  no-record-found condition truly indicates the physical end of
  42.  the library.
  43.  
  44.  3. Internal Organization
  45.     A library must contain at least one member, the directory,
  46.  and may contain an arbitrary number of other members, up to
  47.  the limits of file size imposed by the operating system.  The
  48.  library may also contain unused sectors which are not assigned
  49.  to any member.  These sectors may occur as a result of the
  50.  deletion of members, or of an unsuccessful add operation.
  51.     There are no constraints on the contents of members, except
  52.  for the directory, which is always the first member in the
  53.  library, and has a specific format defined later.  However,
  54.  each member must comprise a whole number of 128 byte sectors;
  55.  i.e. each sector of the file belongs to at most one library
  56.  member, and no member has a fractional number of sectors.  A
  57.  member may have 0 sectors.
  58.     Members may be referred to by a name of up to 8 characters,
  59.  and an extension of up to 3 characters.  The naming rules
  60.  are identical to those for the naming of disk files.
  61.     The start and end points of each member are defined by the
  62.  pointers in the directory entry for the member.  There are no
  63.  embedded start or end marks separating the members.  All
  64.  sectors between the start and end sectors of a member belong
  65.  to that member.
  66.  
  67.  4. Directory Format
  68.     The directory is the first member of a library, and must
  69.  begin in sector 0 of the file.  It must contain at least one
  70.  sector, and may contain an arbitrary number of sectors.
  71.     The directory is composed of entries.  Each entry is 32
  72.  bytes in length, so that the number of entries is equal to
  73.  four times the number of sectors in the directory.  The
  74.  number of entries determines the maximum number of members in
  75.  the library, one entry per member.
  76.     Each entry is initialized to one of three possible states:
  77.  Active, Deleted, or Unused.  The first entry is always active,
  78.  and is the entry corresponding to the directory itself.
  79.     Unused entries always occur after all active and deleted
  80.  entries.  If the directory is scanned beginning with the
  81.  first entry, and an unused entry is found, then all remaining
  82.  entries from there through the end of the directory must also
  83.  be tagged as unused.
  84.     However, active and deleted entries may be mixed in any
  85.  order.  Finding a deleted entry does not guarantee that all
  86.  active entries have been scanned.
  87.  
  88.  5. Directory Entry Format
  89.     The 32 bytes of each entry have the following significance:
  90.                 
  91.         Byte                    Meaning
  92.         ----    ------------------------------------------
  93.         0       STATUS  Possible values (in hexadecimal) are:
  94.                 00      Active Entry
  95.                 FE      Deleted Entry
  96.                 FF      Unused Entry
  97.                         Any other value should be treated as
  98.                         a deleted entry.
  99.  
  100.         1-8     NAME    Rules are identical with those which
  101.                         govern the naming of disk files.  Names
  102.                 shorter than the maximum are padded with
  103.                 spaces.  No two members may have the same name.
  104.                 The name of the directory member (first entry)
  105.                 is all spaces.
  106.  
  107.         9-11    EXTENSION       (same rules as Name)
  108.  
  109.         12-13   INDEX   Pointer to the first sector of this
  110.                         member within the library.  Stored as
  111.                 a two-byte binary value, least significant byte
  112.                 first.  To begin reading at the start of a
  113.                 member, this value is loaded into the Random
  114.                 Record field of the File Control Block.  The
  115.                 index of the directory itself is zero.
  116.  
  117.         14-15   LENGTH  The length of the member in sectors.
  118.                         Stored as a two-byte binary value,
  119.                 least significant byte first.  If this value is
  120.                 zero, then the member is null, and the Index
  121.                 field (above) is meaningless.
  122.  
  123.         16-17   CRC     The Cyclic Redundancy Check value for
  124.                         the member.  Stored as a two-byte
  125.                 binary value, least significant byte first.
  126.                 This value is calculated using the same
  127.                 algorithm as the widely distributed XMODEM
  128.                 program using CRC protocol.  If each byte of
  129.                 the member file is processed by this algorithm,
  130.                 followed by the two bytes of the CRC itself
  131.                 (high order first), the resulting value will be
  132.                 zero.
  133.                    The directory member is a special case. Its
  134.                 own CRC value is embedded within it, which
  135.                 would affect the outcome of the next CRC check.
  136.                 For this reason, The CRC value for the
  137.                 directory's own entry is calculated as if the
  138.                 two bytes of its own CRC word were 00.  The
  139.                 actual value is plugged in just before writing 
  140.                 to disk.  When checking the directory CRC, the 
  141.                 value is moved  to a hold area, and these two
  142.                 bytes are zeroed before the calculation.
  143.  
  144. |               The next four 16-bit words are reserved for library
  145. |               member time and date stamping.  These words are defined
  146. |               below, and must be stored INTEL HEX format with the
  147. |               least significant byte stored first.
  148. |
  149. |       18-19   FILE CREATION DATE.  Stored in Digital Research
  150. |               MP/M - CP/M+ julian date format, as a binary
  151. |               number representing the number of days since
  152. |               December 31, 1977.  For example:  Jan 1, 1978 is
  153. |               1 (0001H), and July 4, 1984 is 2377 (0949H).  If
  154. |               this feature is not used, it should be zero filled
  155. |               to retain compatibility.  For use in MS-DOS
  156. |               environments, convert the MS-DOS yy/mm/dd date
  157. |               to the DRI format, and store in this word.
  158. |
  159. |       20-21   FILE UPDATE/CHANGE DATE.  Stored in Digital Research
  160. |               MP/M - CP/M+ julian date format.  If this feature is
  161. |               not used, it should be zero filled to retain
  162. |               compatibility.
  163. |
  164. |       22-23   FILE CREATION TIME.  Stored in MS-DOS format:
  165. |
  166. |       ------------  23  ------------  ------------  22  ------------
  167. |       15  14  13  12  11  10  09  08  07  06  05  04  03  02  01  00
  168. |        h   h   h   h   h   m   m   m   m   m   m   s   s   s   s   s
  169. |
  170. |               h = binary number of hours (0-23).
  171. |               m = binary number of minutes (0-59).
  172. |               s = binary number of two-second increments.
  173. |
  174. |               Use this field for time-stamping in MS-DOS
  175. |               environments.  If this feature is not used
  176. |               it should be zero-filled.
  177. |
  178. |       24-25   FILE UPDATE/CHANGE TIME.  Stored in MS-DOS
  179. |               format.  In an MS-DOS environment, or if this
  180. |               feature is not implemented, this field
  181. |               should be zero filled.
  182. |
  183. |       26-31   FILLER  Reserved for future use.  In unused
  184.                         and deleted entries, these bytes are
  185.         garbage.  In all active entries, including the first
  186.         (directory) entry, they are explicitly set to binary
  187.         zero.  This is a difference from previously published
  188.         definitions, which did not define the contents of these
  189.         bytes in the directory control entry.
  190.            Any future enhancements to the .LBR format which
  191.         make use of these bytes will recognize this zero
  192.         value as a non-error condition to allow a library
  193.         created with an old version of LU to be processed by
  194.         future versions.
  195.  
  196.  Notes:
  197.         In unused and deleted entries all bytes except the
  198.         Status byte are undefined.
  199.  
  200.            The contents of any data sectors which are not
  201.         assigned to an active member are not defined.
  202.         They remain allocated to the .LBR file, to provide
  203.         for sequential processing, as noted above, but no
  204.         assumptions should be made as to their contents.
  205.         These sectors are eliminated from the library when
  206.         it is reorganized.
  207.  
  208.         For systems which do not implement the CRC validation
  209.         functions, the crc value of member entries should
  210.         be set to 0000.  The last 16 bytes of the directory
  211.         control (first) entry should all be set to a non-zero
  212.         value.  This will prevent CRC-capable versions of
  213.         the program from issuing CRC error messages when
  214.         opening or extracting from an old-style library
  215.  
  216.  6. Conclusion
  217.     If there are any further questions, comments, or requests
  218.  regarding library format, or if you note any ambiguities or
  219.  contradictions in these specifications, please feel free to
  220.  contact me.
  221.  
  222.         Gary P. Novosielski
  223.  
  224.         Voice phone: (201) 935-4087  Evenings and weekends
  225.         CompuServe:  [70160,120]     EMAIL or CP-MIG
  226.  
  227.  
  228.  
  229.  End of file.
  230.  
  231.  
  232. Press ENTER to continue: venings and weekends
  233.         Compuerve:  [70160,120]     EMAIL or CP-MIG
  234.  
  235.  
  236.  
  237.  End of file.
  238.  
  239.  
  240. Press ENTER to continue: venings and weekends
  241.         Compu